'\" p
.\" -*- nroff -*-
.TH "ovn-nb" 5 " DB Schema 2.0.1" "Open vSwitch 2.5.0" "Open vSwitch Manual"
.fp 5 L CR              \\" Make fixed-width font available as \\fL.
.de TQ
.  br
.  ns
.  TP "\\$1"
..
.de ST
.  PP
.  RS -0.15in
.  I "\\$1"
.  RE
..
.SH NAME
ovn-nb \- OVN_Northbound database schema
.PP
This database is the interface between OVN and the cloud management system
(CMS), such as OpenStack, running above it\[char46]  The CMS produces almost all of
the contents of the database\[char46]  The \fBovn\-northd\fR program
monitors the database contents, transforms it, and stores it into the \fBOVN_Southbound\fR database\[char46]
.PP
We generally speak of ``the\(cq\(cq CMS, but one can imagine scenarios in
which multiple CMSes manage different parts of an OVN deployment\[char46]
.SS "External IDs"
.PP
Each of the tables in this database contains a special column, named
\fBexternal_ids\fR\[char46]  This column has the same form and purpose each
place it appears\[char46]
.RS
.TP
\fBexternal_ids\fR: map of string-string pairs
Key-value pairs for use by the CMS\[char46]  The CMS might use certain pairs, for
example, to identify entities in its own configuration that correspond to
those in this database\[char46]
.RE
.SH "TABLE SUMMARY"
.PP
The following list summarizes the purpose of each of the tables in the
\fBOVN_Northbound\fR database.  Each table is described in more detail on a later
page.
.IP "Table" 1in
Purpose
.TQ 1in
\fBLogical_Switch\fR
L2 logical switch
.TQ 1in
\fBLogical_Port\fR
L2 logical switch port
.TQ 1in
\fBACL\fR
Access Control List (ACL) rule
.TQ 1in
\fBLogical_Router\fR
L3 logical router
.TQ 1in
\fBLogical_Router_Port\fR
L3 logical router port
.bp
.SH "Logical_Switch TABLE"
Each row represents one L2 logical switch\[char46]
.SS "Summary:
.TQ 3.00in
\fBname\fR
string
.TQ 3.00in
\fBports\fR
set of \fBLogical_Port\fRs
.TQ 3.00in
\fBacls\fR
set of \fBACL\fRs
.TQ .25in
\fICommon Columns:\fR
.RS .25in
.TQ 2.75in
\fBexternal_ids\fR
map of string-string pairs
.RE
.SS "Details:
.IP "\fBname\fR: string"
A name for the logical switch\[char46]  This name has no special meaning or purpose
other than to provide convenience for human interaction with the ovn-nb
database\[char46]  There is no requirement for the name to be unique\[char46]  The
logical switch\(cqs UUID should be used as the unique identifier\[char46]
.IP "\fBports\fR: set of \fBLogical_Port\fRs"
The logical ports connected to the logical switch\[char46]
.IP
It is an error for multiple logical switches to include the same
logical port\[char46]
.IP "\fBacls\fR: set of \fBACL\fRs"
Access control rules that apply to packets within the logical switch\[char46]
.ST "Common Columns:"
.IP "\fBexternal_ids\fR: map of string-string pairs"
See \fBExternal IDs\fR at the beginning of this document\[char46]
.bp
.SH "Logical_Port TABLE"
A port within an L2 logical switch\[char46]
.SS "Summary:
.TQ .25in
\fICore Features:\fR
.RS .25in
.TQ 2.75in
\fBname\fR
string (must be unique within table)
.TQ 2.75in
\fBtype\fR
string
.RE
.TQ .25in
\fIOptions:\fR
.RS .25in
.TQ 2.75in
\fBoptions\fR
map of string-string pairs
.TQ .25in
\fIOptions for router ports:\fR
.RS .25in
.TQ 2.50in
\fBoptions : router-port\fR
optional string
.RE
.TQ .25in
\fIOptions for localnet ports:\fR
.RS .25in
.TQ 2.50in
\fBoptions : network_name\fR
optional string
.RE
.TQ .25in
\fIOptions for vtep ports:\fR
.RS .25in
.TQ 2.50in
\fBoptions : vtep-physical-switch\fR
optional string
.TQ 2.50in
\fBoptions : vtep-logical-switch\fR
optional string
.RE
.RE
.TQ .25in
\fIContainers:\fR
.RS .25in
.TQ 2.75in
\fBparent_name\fR
optional string
.TQ 2.75in
\fBtag\fR
optional integer, in range 1 to 4,095
.RE
.TQ .25in
\fIPort State:\fR
.RS .25in
.TQ 2.75in
\fBup\fR
optional boolean
.TQ 2.75in
\fBenabled\fR
optional boolean
.RE
.TQ .25in
\fIAddressing:\fR
.RS .25in
.TQ 2.75in
\fBaddresses\fR
set of strings
.TQ 2.75in
\fBport_security\fR
set of strings
.RE
.TQ .25in
\fICommon Columns:\fR
.RS .25in
.TQ 2.75in
\fBexternal_ids\fR
map of string-string pairs
.RE
.SS "Details:
.ST "Core Features:"
.IP "\fBname\fR: string (must be unique within table)"
The logical port name\[char46]
.IP
For entities (VMs or containers) that are spawned in the hypervisor,
the name used here must match those used in the \fBexternal_ids:iface-id\fR in the
\fBOpen_vSwitch\fR database\(cqs \fBInterface\fR table, because hypervisors use \fBexternal_ids:iface-id\fR as a lookup
key to identify the network interface of that entity\[char46]
.IP
For containers that share a VIF within a VM, the name can be any
unique identifier\[char46]  See \fBContainers\fR, below, for more
information\[char46]
.IP "\fBtype\fR: string"
Specify a type for this logical port\[char46]  Logical ports can be used to
model other types of connectivity into an OVN logical switch\[char46]  The
following types are defined:
.RS
.TP
(empty string)
A VM (or VIF) interface\[char46]
.TP
\fBrouter\fR
A connection to a logical router\[char46]
.TP
\fBlocalnet\fR
A connection to a locally accessible network from each
\fBovn\-controller\fR instance\[char46]  A logical switch can only
have a single \fBlocalnet\fR port attached and at most one
regular logical port\[char46]  This is used to model direct connectivity to
an existing network\[char46]
.TP
\fBvtep\fR
A port to a logical switch on a VTEP gateway\[char46]
.RE
.ST "Options:"
.IP "\fBoptions\fR: map of string-string pairs"
This column provides key/value settings specific to the logical port
\fBtype\fR\[char46]  The type-specific options are described
individually below\[char46]
.ST "Options for router ports:"
These options apply when \fBtype\fR is \fBrouter\fR\[char46]
.PP
If a given logical switch has multiple \fBrouter\fR ports, the
\fBLogical_Router_Port\fR rows that they reference must be
all on the same \fBLogical_Router\fR (for different
subnets)\[char46]
.IP "\fBoptions : router-port\fR: optional string"
Required\[char46]  The \fBname\fR of the \fBLogical_Router_Port\fR to which this logical switch port is
connected\[char46]
.ST "Options for localnet ports:"
These options apply when \fBtype\fR is
\fBlocalnet\fR\[char46]
.IP "\fBoptions : network_name\fR: optional string"
Required\[char46]  The name of the network to which the \fBlocalnet\fR
port is connected\[char46]  Each hypervisor, via \fBovn\-controller\fR,
uses its local configuration to determine exactly how to connect to
this locally accessible network\[char46]
.ST "Options for vtep ports:"
These options apply when \fBtype\fR is \fBvtep\fR\[char46]
.IP "\fBoptions : vtep-physical-switch\fR: optional string"
Required\[char46]  The name of the VTEP gateway\[char46]
.IP "\fBoptions : vtep-logical-switch\fR: optional string"
Required\[char46]  A logical switch name connected by the VTEP gateway\[char46]
.ST "Containers:"
When a large number of containers are nested within a VM, it may be too
expensive to dedicate a VIF to each container\[char46]  OVN can use VLAN tags
to support such cases\[char46]  Each container is assigned a VLAN ID and each
packet that passes between the hypervisor and the VM is tagged with the
appropriate ID for the container\[char46]  Such VLAN IDs never appear on a
physical wire, even inside a tunnel, so they need not be unique except
relative to a single VM on a hypervisor\[char46]
.PP
These columns are used for VIFs that represent nested containers using
shared VIFs\[char46]  For VMs and for containers that have dedicated VIFs, they
are empty\[char46]
.IP "\fBparent_name\fR: optional string"
The VM interface through which the nested container sends its network
traffic\[char46]  This must match the \fBname\fR column for some
other \fBLogical_Port\fR\[char46]
.IP "\fBtag\fR: optional integer, in range 1 to 4,095"
The VLAN tag in the network traffic associated with a container\(cqs
network interface\[char46]
.IP
When \fBtype\fR is set to \fBlocalnet\fR, this can
be set to indicate that the port represents a connection to a
specific VLAN on a locally accessible network\[char46] The VLAN ID is used to
match incoming traffic and is also added to outgoing traffic\[char46]
.ST "Port State:"
.IP "\fBup\fR: optional boolean"
This column is populated by \fBovn\-northd\fR, rather than by the
CMS plugin as is most of this database\[char46]  When a logical port is bound
to a physical location in the OVN Southbound database \fBBinding\fR table, \fBovn\-northd\fR
sets this column to \fBtrue\fR; otherwise, or if the port
becomes unbound later, it sets it to \fBfalse\fR\[char46]  This allows
the CMS to wait for a VM\(cqs (or container\(cqs) networking to become active
before it allows the VM (or container) to start\[char46]
.IP "\fBenabled\fR: optional boolean"
This column is used to administratively set port state\[char46]  If this column
is empty or is set to \fBtrue\fR, the port is enabled\[char46]  If this
column is set to \fBfalse\fR, the port is disabled\[char46]  A disabled
port has all ingress and egress traffic dropped\[char46]
.ST "Addressing:"
.IP "\fBaddresses\fR: set of strings"
Addresses owned by the logical port\[char46]
.IP
Each element in the set must take one of the following forms:
.RS
.TP
\fB\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB\fR
An Ethernet address owned by the logical port\[char46]  Like a physical
Ethernet NIC, a logical port ordinarily has a single fixed
Ethernet address\[char46]
.IP
When a OVN logical switch processes a unicast Ethernet frame
whose destination MAC address is in a logical port\(cqs \fBaddresses\fR column, it delivers it only to that port, as
if a MAC learning process had learned that MAC address on the
port\[char46]
.TP
\fB\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB \fIa\fB\[char46]\fIb\fB\[char46]\fIc\fB\[char46]\fId\fB\fR
This form has all the effects of the previous form\[char46]  It also
indicates that the logical port owns the given IPv4 address\[char46]
.IP
The OVN logical switch uses this information to synthesize
responses to ARP requests without traversing the physical
network\[char46]  The OVN logical router connected to the logical switch,
if any, uses this information to avoid issuing ARP requests for
logical switch ports\[char46]
.IP
Note that the order here is important\[char46] The Ethernet address must
be listed before the IP address\[char46]
.TP
\fBunknown\fR
This indicates that the logical port has an unknown set of Ethernet
addresses\[char46]  When an OVN logical switch processes a unicast Ethernet
frame whose destination MAC address is not in any logical port\(cqs
\fBaddresses\fR column, it delivers it to the port (or
ports) whose \fBaddresses\fR columns include
\fBunknown\fR\[char46]
.RE
.IP "\fBport_security\fR: set of strings"
A set of L2 (Ethernet) addresses from which the logical port is
allowed to send packets and to which it is allowed to receive
packets\[char46]  If this column is empty, all addresses are permitted\[char46]
Logical ports are always allowed to receive packets addressed to
multicast and broadcast addresses\[char46]
.IP
Each member of the set is an Ethernet address in the form
\fIxx\fR:\fIxx\fR:\fIxx\fR:\fIxx\fR:\fIxx\fR:\fIxx\fR\[char46]
.IP
This specification will be extended to support L3 port security\[char46]
.ST "Common Columns:"
.IP "\fBexternal_ids\fR: map of string-string pairs"
See \fBExternal IDs\fR at the beginning of this document\[char46]
.bp
.SH "ACL TABLE"
Each row in this table represents one ACL rule for a logical switch
that points to it through its \fBacls\fR column\[char46]  The \fBaction\fR column for the highest-\fBpriority\fR
matching row in this table determines a packet\(cqs treatment\[char46]  If no row
matches, packets are allowed by default\[char46]  (Default-deny treatment is
possible: add a rule with \fBpriority\fR 0, \fB0\fR as
\fBmatch\fR, and \fBdeny\fR as \fBaction\fR\[char46])
.SS "Summary:
.TQ 3.00in
\fBpriority\fR
integer, in range 0 to 32,767
.TQ 3.00in
\fBdirection\fR
string, either \fBto\-lport\fR or \fBfrom\-lport\fR
.TQ 3.00in
\fBmatch\fR
string
.TQ 3.00in
\fBaction\fR
string, one of \fBallow\-related\fR, \fBdrop\fR, \fBallow\fR, or \fBreject\fR
.TQ 3.00in
\fBlog\fR
boolean
.TQ .25in
\fICommon Columns:\fR
.RS .25in
.TQ 2.75in
\fBexternal_ids\fR
map of string-string pairs
.RE
.SS "Details:
.IP "\fBpriority\fR: integer, in range 0 to 32,767"
The ACL rule\(cqs priority\[char46]  Rules with numerically higher priority
take precedence over those with lower\[char46]  If two ACL rules with
the same priority both match, then the one actually applied to a
packet is undefined\[char46]
.IP
Return traffic from an \fBallow\-related\fR flow is always
allowed and cannot be changed through an ACL\[char46]
.IP "\fBdirection\fR: string, either \fBto\-lport\fR or \fBfrom\-lport\fR"
Direction of the traffic to which this rule should apply:
.RS
.IP \(bu
\fBfrom\-lport\fR: Used to implement filters on traffic
arriving from a logical port\[char46]  These rules are applied to the
logical switch\(cqs ingress pipeline\[char46]
.IP \(bu
\fBto\-lport\fR: Used to implement filters on traffic
forwarded to a logical port\[char46]  These rules are applied to the
logical switch\(cqs egress pipeline\[char46]
.RE
.IP "\fBmatch\fR: string"
The packets that the ACL should match, in the same expression
language used for the \fBmatch\fR column in the OVN Southbound database\(cqs
\fBLogical_Flow\fR table\[char46]  The
\fBoutport\fR logical port is only available in the
\fBto\-lport\fR direction (the \fBinport\fR is
available in both directions)\[char46]
.IP
By default all traffic is allowed\[char46]  When writing a more
restrictive policy, it is important to remember to allow flows
such as ARP and IPv6 neighbor discovery packets\[char46]
.IP
Note that you can not create an ACL matching on a port with
type=router\[char46]
.IP "\fBaction\fR: string, one of \fBallow\-related\fR, \fBdrop\fR, \fBallow\fR, or \fBreject\fR"
The action to take when the ACL rule matches:
.RS
.IP \(bu
\fBallow\fR: Forward the packet\[char46]
.IP \(bu
\fBallow\-related\fR: Forward the packet and related traffic
(e\[char46]g\[char46] inbound replies to an outbound connection)\[char46]
.IP \(bu
\fBdrop\fR: Silently drop the packet\[char46]
.IP \(bu
\fBreject\fR: Drop the packet, replying with a RST for TCP or
ICMP unreachable message for other IP-based protocols\[char46]
\fBNot implemented\-\-currently treated as drop\fR
.RE
.IP "\fBlog\fR: boolean"
If set to \fBtrue\fR, packets that match the ACL will trigger a
log message on the transport node or nodes that perform ACL processing\[char46]
Logging may be combined with any \fBaction\fR\[char46]
.IP
Logging is not yet implemented\[char46]
.ST "Common Columns:"
.IP "\fBexternal_ids\fR: map of string-string pairs"
See \fBExternal IDs\fR at the beginning of this document\[char46]
.bp
.SH "Logical_Router TABLE"
Each row represents one L3 logical router\[char46]
.SS "Summary:
.TQ 3.00in
\fBname\fR
string
.TQ 3.00in
\fBports\fR
set of \fBLogical_Router_Port\fRs
.TQ 3.00in
\fBdefault_gw\fR
optional string
.TQ .25in
\fICommon Columns:\fR
.RS .25in
.TQ 2.75in
\fBexternal_ids\fR
map of string-string pairs
.RE
.SS "Details:
.IP "\fBname\fR: string"
A name for the logical router\[char46]  This name has no special meaning or purpose
other than to provide convenience for human interaction with the ovn-nb
database\[char46]  There is no requirement for the name to be unique\[char46]  The
logical router\(cqs UUID should be used as the unique identifier\[char46]
.IP "\fBports\fR: set of \fBLogical_Router_Port\fRs"
The router\(cqs ports\[char46]
.IP "\fBdefault_gw\fR: optional string"
IP address to use as default gateway, if any\[char46]
.ST "Common Columns:"
.IP "\fBexternal_ids\fR: map of string-string pairs"
See \fBExternal IDs\fR at the beginning of this document\[char46]
.bp
.SH "Logical_Router_Port TABLE"
A port within an L3 logical router\[char46]
.PP
Exactly one \fBLogical_Router\fR row must reference a given
logical router port\[char46]
.SS "Summary:
.TQ 3.00in
\fBname\fR
string (must be unique within table)
.TQ 3.00in
\fBnetwork\fR
string
.TQ 3.00in
\fBmac\fR
string
.TQ 3.00in
\fBenabled\fR
optional boolean
.TQ .25in
\fIAttachment:\fR
.RS .25in
.TQ 2.75in
\fBpeer\fR
optional \fBLogical_Router_Port\fR
.RE
.TQ .25in
\fICommon Columns:\fR
.RS .25in
.TQ 2.75in
\fBexternal_ids\fR
map of string-string pairs
.RE
.SS "Details:
.IP "\fBname\fR: string (must be unique within table)"
A name for the logical router port\[char46]
.IP
In addition to provide convenience for human interaction with the
ovn-nb database, this column is used as reference by its patch port in
\fBLogical_Port\fR or another logical router port in \fBLogical_Router_Port\fR\[char46]
.IP "\fBnetwork\fR: string"
The IP address of the router and the netmask\[char46]  For example,
\fB192\[char46]168\[char46]0\[char46]1/24\fR indicates that the router\(cqs IP address is
192\[char46]168\[char46]0\[char46]1 and that packets destined to 192\[char46]168\[char46]0\[char46]\fIx\fR should be
routed to this port\[char46]
.IP "\fBmac\fR: string"
The Ethernet address that belongs to this router port\[char46]
.IP "\fBenabled\fR: optional boolean"
This column is used to administratively set port state\[char46]  If this column
is empty or is set to \fBtrue\fR, the port is enabled\[char46]  If this
column is set to \fBfalse\fR, the port is disabled\[char46]  A disabled
port has all ingress and egress traffic dropped\[char46]
.ST "Attachment:"
A given router port serves one of two purposes:
.RS
.IP \(bu
To attach a logical switch to a logical router\[char46]  A logical router
port of this type is referenced by exactly one \fBLogical_Port\fR of type \fBrouter\fR\[char46]  The value of
\fBname\fR is set as \fBrouter\-port\fR in column
\fBoptions\fR of \fBLogical_Port\fR\[char46]
In this case \fBpeer\fR column is empty\[char46]
.IP \(bu
To connect one logical router to another\[char46]  This requires a pair of
logical router ports, each connected to a different router\[char46]  Each
router port in the pair specifies the other in its \fBpeer\fR column\[char46]  No \fBLogical_Switch\fR refers to
the router port\[char46]
.RE
.IP "\fBpeer\fR: optional \fBLogical_Router_Port\fR"
For a router port used to connect two logical routers, this
identifies the other router port in the pair by \fBname\fR\[char46]
.IP
For a router port attached to a logical switch, this column is empty\[char46]
.ST "Common Columns:"
.IP "\fBexternal_ids\fR: map of string-string pairs"
See \fBExternal IDs\fR at the beginning of this document\[char46]
